فیلتر دستگاه WebHID در فرانت‌اند: راهنمای انتخاب دستگاه رابط انسانی (HID)

API وب‌سایت WebHID دنیایی از امکانات را برای اپلیکیشن‌های وب باز می‌کند و به آن‌ها اجازه می‌دهد تا مستقیماً با دستگاه‌های رابط انسانی (HID) مانند گیم‌پدها، دستگاه‌های ورودی تخصصی و موارد دیگر تعامل داشته باشند. بخش حیاتی استفاده مؤثر از WebHID، درک فیلترهای دستگاه است. این راهنمای جامع شما را با جزئیات فیلترهای دستگاه WebHID آشنا می‌کند تا بتوانید تجربه‌های وب قدرتمند و جذابی ایجاد کنید.

WebHID چیست؟

WebHID یک API وب است که به اپلیکیشن‌های وب امکان می‌دهد با دستگاه‌های HID متصل به کامپیوتر یا دستگاه موبایل کاربر ارتباط برقرار کنند. برخلاف APIهای وب سنتی که به درایورهای دستگاه خاصی متکی هستند، WebHID یک رابط عمومی برای تعامل با طیف گسترده‌ای از دستگاه‌ها فراهم می‌کند، به شرطی که کاربر اجازه دسترسی را صادر کند. این ویژگی آن را برای دستگاه‌هایی که پشتیبانی بومی در مرورگر ندارند یا به مدیریت ورودی سفارشی نیاز دارند، ایده‌آل می‌سازد.

چرا از WebHID استفاده کنیم؟

• دسترسی مستقیم به دستگاه: بدون اتکا به درایورهای مخصوص مرورگر، مستقیماً با دستگاه‌های HID ارتباط برقرار کنید.
• مدیریت ورودی سفارشی: نگاشت و پردازش ورودی سفارشی را برای دستگاه‌های تخصصی پیاده‌سازی کنید.
• پشتیبانی گسترده از دستگاه‌ها: از طیف وسیع‌تری از دستگاه‌ها، از جمله گیم‌پدها، ابزارهای علمی و کنترل‌کننده‌های صنعتی پشتیبانی کنید.
• تجربه کاربری بهبودیافته: تجربه‌های وب فراگیرتر و تعاملی‌تری ایجاد کنید.

درک فیلترهای دستگاه WebHID

فیلترهای دستگاه برای درخواست دسترسی به دستگاه‌های HID خاص بسیار حیاتی هستند. هنگامی که اپلیکیشن وب شما متد navigator.hid.requestDevice() را فراخوانی می‌کند، مرورگر یک انتخابگر دستگاه نمایش می‌دهد که به کاربر اجازه می‌دهد یک دستگاه را انتخاب کند. فیلترهای دستگاه به شما این امکان را می‌دهند که لیست دستگاه‌های ارائه‌شده به کاربر را محدود کنید و پیدا کردن دستگاه صحیح را برای او آسان‌تر سازید.

فیلتر دستگاه یک شیء جاوا اسکریپت است که معیارهایی را برای تطبیق دستگاه‌های HID مشخص می‌کند. شما می‌توانید چندین فیلتر را در فراخوانی requestDevice() مشخص کنید و مرورگر فقط دستگاه‌هایی را نشان می‌دهد که حداقل با یکی از فیلترها مطابقت داشته باشند.

ویژگی‌های فیلتر دستگاه

ویژگی‌های زیر می‌توانند در یک فیلتر دستگاه WebHID استفاده شوند:

• vendorId (اختیاری): شناسه فروشنده USB دستگاه. این یک عدد ۱۶ بیتی است که سازنده دستگاه را مشخص می‌کند.
• productId (اختیاری): شناسه محصول USB دستگاه. این یک عدد ۱۶ بیتی است که مدل خاص دستگاه را مشخص می‌کند.
• usagePage (اختیاری): صفحه کاربرد (Usage Page) HID دستگاه. این ویژگی دسته دستگاه را مشخص می‌کند (مثلاً، کنترل‌های دسکتاپ عمومی، کنترل‌های بازی).
• usage (اختیاری): کاربرد (Usage) HID دستگاه. این ویژگی عملکرد خاص دستگاه در صفحه کاربرد را مشخص می‌کند (مثلاً، جوی‌استیک، گیم‌پد).

شما می‌توانید از ترکیبی از این ویژگی‌ها برای ایجاد فیلترهای بسیار دقیق استفاده کنید. برای مثال، ممکن است بخواهید برای دستگاه‌هایی با vendorId و productId خاص فیلتر کنید تا یک مدل خاص از گیم‌پد را هدف قرار دهید.

مثال‌های عملی از فیلترهای دستگاه

بیایید به چند مثال عملی از نحوه استفاده از فیلترهای دستگاه در اپلیکیشن‌های وب خود نگاهی بیندازیم.

مثال ۱: فیلتر کردن برای یک گیم‌پد خاص

فرض کنید می‌خواهید یک گیم‌پد خاص با vendorId و productId مشخص را هدف قرار دهید. می‌توانید از فیلتر زیر استفاده کنید:

            const filters = [
  {
    vendorId: 0x045e, // Microsoft
    productId: 0x028e, // Xbox 360 Controller
  },
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Handle the selected device(s)
  })
  .catch((error) => {
    // Handle errors
  });

            

              
                Copy
              
            
          

در این مثال، فیلتر فقط با دستگاه‌هایی با vendorId برابر با 0x045e (مایکروسافت) و productId برابر با 0x028e (کنترلر Xbox 360) مطابقت خواهد داشت. این مقادیر را با شناسه فروشنده و شناسه محصول مناسب دستگاه مورد نظر خود جایگزین کنید.

مثال ۲: فیلتر کردن برای هر نوع گیم‌پد

اگر می‌خواهید به کاربر اجازه دهید هر نوع گیم‌پدی را انتخاب کند، می‌توانید از فیلتری استفاده کنید که usagePage و usage مربوط به گیم‌پدها را مشخص می‌کند:

            const filters = [
  {
    usagePage: 0x01, // Generic Desktop Controls
    usage: 0x05, // Gamepad
  },
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Handle the selected device(s)
  })
  .catch((error) => {
    // Handle errors
  });

            

              
                Copy
              
            
          

این فیلتر با هر دستگاه HID که خود را با استفاده از کدهای استاندارد کاربرد HID به عنوان گیم‌پد معرفی کند، مطابقت خواهد داشت.

مثال ۳: ترکیب فیلترها

شما می‌توانید چندین فیلتر را برای ارائه انعطاف‌پذیری بیشتر ترکیب کنید. برای مثال، ممکن است بخواهید به کاربر اجازه دهید یا یک مدل گیم‌پد خاص را انتخاب کند یا هر نوع گیم‌پد دیگری را:

            const filters = [
  {
    vendorId: 0x045e, // Microsoft
    productId: 0x028e, // Xbox 360 Controller
  },
  {
    usagePage: 0x01, // Generic Desktop Controls
    usage: 0x05, // Gamepad
  },
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Handle the selected device(s)
  })
  .catch((error) => {
    // Handle errors
  });

            

              
                Copy
              
            
          

در این حالت، انتخابگر دستگاه هم کنترلر خاص Xbox 360 (در صورت اتصال) و هم هر دستگاه دیگری که خود را به عنوان گیم‌پد معرفی کند، نمایش خواهد داد.

مثال ۴: فیلتر کردن برای یک نوع کیبورد خاص در سیستم

برخی کیبوردهای خاص برای راه‌اندازی صحیح به کدهای HID ویژه‌ای نیاز دارند. مثال زیر فرض می‌کند که شما شناسه فروشنده، شناسه محصول، صفحه کاربرد و کاربرد کیبورد را می‌دانید. معمولاً می‌توانید این اطلاعات را از مستندات سازنده یا با استفاده از ابزارهای لیست کردن دستگاه‌ها که در اکثر سیستم‌عامل‌ها موجود است، پیدا کنید.

            const filters = [
    {
        vendorId: 0x1234,  // Replace with your vendor ID
        productId: 0x5678, // Replace with your product ID
        usagePage: 0x07,   // Replace with your usage page (e.g., Keyboard/Keypad)
        usage: 0x01      // Replace with your usage (e.g., Keyboard)
    }
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Handle the selected device(s)
  })
  .catch((error) => {
    // Handle errors
  });

            

              
                Copy
              
            
          

دریافت اطلاعات دستگاه

پس از اینکه کاربر یک دستگاه را انتخاب کرد، می‌توانید با استفاده از شیء HIDDevice به اطلاعات آن دسترسی پیدا کنید.

ویژگی‌های HIDDevice

• vendorId: شناسه فروشنده USB دستگاه.
• productId: شناسه محصول USB دستگاه.
• productName: نام دستگاه.
• collections: آرایه‌ای از اشیاء HIDCollection که توصیف‌گرهای گزارش HID دستگاه را نشان می‌دهند.

شما می‌توانید از این اطلاعات برای شناسایی دستگاه و پیکربندی اپلیکیشن خود بر اساس آن استفاده کنید.

مدیریت گزارش‌های HID

پس از به دست آوردن یک HIDDevice، باید آن را باز کرده و شروع به گوش دادن به گزارش‌های HID کنید. گزارش‌های HID داده‌های خامی هستند که توسط دستگاه به اپلیکیشن شما ارسال می‌شوند.

باز کردن دستگاه

            device.open()
  .then(() => {
    console.log('Device opened');

    // Start listening for input reports
    device.addEventListener('inputreport', (event) => {
      const { data, reportId } = event;
      // Process the input report
      console.log(`Received input report with ID ${reportId}:`, data);
    });
  })
  .catch((error) => {
    console.error('Failed to open device:', error);
  });

            

              
                Copy
              
            
          

پردازش گزارش‌های ورودی

گزارش‌های ورودی به صورت اشیاء DataView دریافت می‌شوند. ساختار داده‌ها به توصیف‌گر گزارش HID دستگاه بستگی دارد. شما باید به مستندات دستگاه مراجعه کنید تا نحوه تفسیر داده‌ها را درک کنید.

در اینجا یک مثال ساده از نحوه پردازش یک گزارش ورودی آورده شده است:

            device.addEventListener('inputreport', (event) => {
  const { data, reportId } = event;

  // Assuming the first byte of the report represents the button state
  const buttonState = data.getUint8(0);

  // Process the button state
  if (buttonState & 0x01) {
    console.log('Button 1 pressed');
  }
  if (buttonState & 0x02) {
    console.log('Button 2 pressed');
  }
});

            

              
                Copy
              
            
          

این یک مثال بسیار ابتدایی است. دستگاه‌های HID در دنیای واقعی اغلب ساختارهای گزارش پیچیده‌تری دارند. مهندسی معکوس گزارش HID می‌تواند فرآیند پیچیده‌ای باشد؛ با این حال، ابزارهایی برای کمک به فرآیند تجزیه (parsing) در دسترس هستند.

مدیریت خطا

هنگام کار با WebHID، مدیریت خطاها به شیوه‌ای مناسب بسیار مهم است. در اینجا برخی از خطاهای رایجی که ممکن است با آنها مواجه شوید، آورده شده است:

• SecurityError: کاربر اجازه دسترسی به دستگاه‌های HID را رد کرده است.
• NotFoundError: هیچ دستگاه منطبقی پیدا نشد.
• InvalidStateError: دستگاه از قبل باز است.
• خطاهای دیگر: خطاهای USB، قطع اتصال غیرمنتظره دستگاه.

همیشه کد WebHID خود را در بلوک‌های try...catch قرار دهید و پیام‌های خطای آموزنده‌ای به کاربر ارائه دهید.

بهترین شیوه‌ها برای توسعه WebHID

• از فیلترهای دستگاه استفاده کنید: همیشه از فیلترهای دستگاه برای محدود کردن لیست دستگاه‌های ارائه‌شده به کاربر استفاده کنید.
• دستورالعمل‌های واضح ارائه دهید: کاربران را در مورد نحوه اتصال و صدور مجوز دستگاه راهنمایی کنید، اگر دستگاه ظاهر نشد، به کاربر توضیح دهید که شناسه‌های فروشنده و محصول را برای دستگاه‌های رایج از کجا پیدا کند.
• خطاها را به شیوه‌ای مناسب مدیریت کنید: برای ارائه یک تجربه کاربری روان، مدیریت خطای قوی پیاده‌سازی کنید.
• به مستندات دستگاه مراجعه کنید: برای درک توصیف‌گر گزارش HID دستگاه، به مستندات آن مراجعه کنید.
• روی پلتفرم‌های مختلف تست کنید: اپلیکیشن خود را روی مرورگرها و سیستم‌عامل‌های مختلف تست کنید تا از سازگاری اطمینان حاصل کنید.
• امنیت را در نظر بگیرید: هنگام کار با ورودی کاربر، به پیامدهای امنیتی توجه داشته باشید. داده‌ها را پاک‌سازی (Sanitize) کنید و از اجرای کدهای غیرقابل اعتماد خودداری کنید.
• گزینه‌های جایگزین ارائه دهید: اگر WebHID پشتیبانی نمی‌شود یا کاربر اجازه دسترسی را رد می‌کند، روش‌های ورودی جایگزین فراهم کنید.

تکنیک‌های پیشرفته

گزارش‌های ویژگی (Feature Reports)

علاوه بر گزارش‌های ورودی، دستگاه‌های HID می‌توانند گزارش‌های ویژگی (feature reports) را نیز ارسال و دریافت کنند. گزارش‌های ویژگی برای پیکربندی دستگاه یا بازیابی وضعیت آن استفاده می‌شوند.

برای ارسال یک گزارش ویژگی، از متد device.sendFeatureReport() استفاده کنید.

            const reportId = 0x01;
const data = new Uint8Array([0x01, 0x02, 0x03]); // Example data

device.sendFeatureReport(reportId, data)
  .then(() => {
    console.log('Feature report sent successfully');
  })
  .catch((error) => {
    console.error('Failed to send feature report:', error);
  });

            

              
                Copy
              
            
          

برای دریافت یک گزارش ویژگی، از متد device.getFeatureReport() استفاده کنید.

            const reportId = 0x01;

device.getFeatureReport(reportId)
  .then((data) => {
    console.log('Received feature report:', data);
  })
  .catch((error) => {
    console.error('Failed to get feature report:', error);
  });

            

              
                Copy
              
            
          

گزارش‌های خروجی (Output Reports)

WebHID همچنین از گزارش‌های خروجی (output reports) پشتیبانی می‌کند که به شما امکان می‌دهد داده‌ها را *به* دستگاه ارسال کنید. برای مثال، ممکن است از گزارش‌های خروجی برای کنترل LEDها یا سایر عملگرها روی دستگاه استفاده کنید.

برای ارسال یک گزارش خروجی، از متد device.sendReport() استفاده کنید.

            const reportId = 0x01;
const data = new Uint8Array([0x01, 0x02, 0x03]); // Example data

device.sendReport(reportId, data)
  .then(() => {
    console.log('Output report sent successfully');
  })
  .catch((error) => {
    console.error('Failed to send output report:', error);
  });

            

              
                Copy
              
            
          

ملاحظات امنیتی

دسترسی به WebHID نیازمند اجازه کاربر است که به کاهش برخی خطرات امنیتی کمک می‌کند. با این حال، همچنان مهم است که از آسیب‌پذیری‌های بالقوه آگاه باشید.

• پاک‌سازی داده‌ها: همیشه داده‌های دریافتی از دستگاه‌های HID را برای جلوگیری از تزریق کد یا حملات دیگر پاک‌سازی (Sanitize) کنید.
• محدودیت‌های مبدأ (Origin): WebHID تابع سیاست همان مبدأ (same-origin policy) است که از دسترسی بین مبدأ به دستگاه‌های HID جلوگیری می‌کند.
• آگاهی کاربر: کاربران را در مورد خطرات اعطای دسترسی به دستگاه‌های HID آموزش دهید و آنها را تشویق کنید که فقط به وب‌سایت‌های مورد اعتماد اجازه دسترسی دهند.

چشم‌اندازها و مثال‌های جهانی

API وب‌سایت WebHID پیامدهای جهانی دارد و به توسعه‌دهندگان امکان می‌دهد اپلیکیشن‌های وبی ایجاد کنند که از طیف گسترده‌ای از دستگاه‌های تولیدکنندگان و مناطق مختلف پشتیبانی می‌کنند. این مثال‌ها را در نظر بگیرید:

• بازی: پشتیبانی از گیم‌پدهای تولیدکنندگان مختلف در کشورهای گوناگون (مانند کنترلرهای پلی‌استیشن سونی، کنترلرهای ایکس‌باکس مایکروسافت، کنترلر نینتندو سوییچ پرو و برندهای کمتر شناخته‌شده از آسیا و اروپا).
• دسترسی‌پذیری: ایجاد دستگاه‌های ورودی سفارشی برای کاربران دارای معلولیت، با در نظر گرفتن استانداردها و ترجیحات دسترسی‌پذیری منطقه‌ای مختلف. به عنوان مثال، کیبوردهای تخصصی یا رابط‌های سوئیچ که برای نیازهای خاص طراحی شده و در طرح‌بندی‌های مختلف موجود هستند.
• اتوماسیون صنعتی: ارتباط با کنترل‌کننده‌ها و سنسورهای صنعتی مورد استفاده در کارخانه‌های تولیدی در سراسر جهان، با پشتیبانی از پروتکل‌های ارتباطی و فرمت‌های داده مختلف.
• تحقیقات علمی: اتصال به ابزارهای علمی مورد استفاده در آزمایشگاه‌های تحقیقاتی در سطح جهان، که به محققان امکان می‌دهد داده‌ها را مستقیماً در اپلیکیشن‌های وب جمع‌آوری و تحلیل کنند. تصور کنید کنترل تجهیزات آزمایشگاهی در دانشگاهی در توکیو از طریق لپ‌تاپ یک محقق در لندن انجام شود.
• آموزش: پشتیبانی از ربات‌های آموزشی و دستگاه‌های تعاملی مورد استفاده در کلاس‌های درس در سراسر جهان، و فراهم کردن تجربه‌های یادگیری عملی برای دانش‌آموزان. این می‌تواند شامل ربات‌های کدنویسی ساخت چین باشد که در کلاسی در برزیل استفاده می‌شوند.

مقایسه WebHID با سایر APIهای وب

شایان ذکر است که WebHID با سایر APIهای وب مرتبط با تعامل با دستگاه چگونه مقایسه می‌شود:

• Gamepad API: Gamepad API یک رابط سطح بالاتر به طور خاص برای گیم‌پدها فراهم می‌کند. WebHID انعطاف‌پذیری و کنترل بیشتری ارائه می‌دهد اما به مدیریت دستی بیشتری برای داده‌های دستگاه نیاز دارد. Gamepad API برای گیم‌پدهای رایج بسیار مناسب است، در حالی که WebHID می‌تواند از دستگاه‌های ورودی غیرمعمول‌تر یا تخصصی‌تر پشتیبانی کند.
• WebUSB API: WebUSB به اپلیکیشن‌های وب اجازه می‌دهد مستقیماً با دستگاه‌های USB ارتباط برقرار کنند. WebHID به طور خاص برای دستگاه‌های رابط انسانی طراحی شده است، در حالی که WebUSB می‌تواند برای طیف گسترده‌تری از دستگاه‌های USB استفاده شود. WebUSB ممکن است برای یک ابزار علمی تخصصی متصل از طریق USB استفاده شود، در حالی که WebHID برای یک کیبورد یا ماوس سفارشی به کار می‌رود.
• Web Serial API: Web Serial امکان ارتباط از طریق پورت‌های سریال را فراهم می‌کند. این برای تعامل با سیستم‌های تعبیه‌شده (embedded systems) و سایر دستگاه‌هایی که از طریق اتصالات سریال ارتباط برقرار می‌کنند، مفید است. یک میکروکنترلر که داده‌ها را از طریق اتصال سریال ارسال می‌کند می‌تواند از Web Serial استفاده کند، در حالی که یک جوی‌استیک سفارشی از WebHID استفاده خواهد کرد.

آینده WebHID

API وب‌سایت WebHID به طور مداوم در حال تکامل است و تلاش‌های مستمری برای بهبود امنیت، عملکرد و سهولت استفاده از آن در حال انجام است. با پذیرش استاندارد HID توسط دستگاه‌های بیشتر، WebHID به ابزاری به طور فزاینده مهم برای توسعه‌دهندگان وب تبدیل خواهد شد. در آینده انتظار می‌رود ویژگی‌های پیشرفته‌تر و پشتیبانی بهتر مرورگرها را شاهد باشیم.

نتیجه‌گیری

WebHID یک API قدرتمند است که طیف گسترده‌ای از امکانات را برای اپلیکیشن‌های وب باز می‌کند. با درک فیلترهای دستگاه و نحوه مدیریت گزارش‌های HID، می‌توانید تجربه‌های وب جذاب و تعاملی ایجاد کنید که از پتانسیل کامل دستگاه‌های رابط انسانی بهره می‌برند. چه در حال ساخت یک بازی، یک ابزار دسترسی‌پذیری، یا یک سیستم کنترل صنعتی باشید، WebHID می‌تواند به شما کمک کند تا اپلیکیشن وب خود را به دنیای فیزیکی متصل کنید. به یاد داشته باشید که برای ایجاد اپلیکیشن‌های WebHID موفق و قابل دسترس در سطح جهانی، تجربه کاربری، امنیت و سازگاری بین پلتفرمی را در اولویت قرار دهید.